-
Notifications
You must be signed in to change notification settings - Fork 0
feat: Add composable base schemas and validation patterns to Zod protocol specifications #554
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
- Create base-schemas.zod.ts with 9 reusable composition patterns - Add validation-patterns.zod.ts with regex constants and length constraints - Implement TimestampedSchema, AuditableSchema, SoftDeletableSchema - Add NamedEntitySchema, VersionableSchema, TaggableSchema - Include OwnableSchema, ActivatableSchema, MetadataContainerSchema - Define 20+ regex patterns (snake_case, semver, email, UUID, etc.) - Establish LENGTH_CONSTRAINTS for consistent field validation - Add comprehensive test coverage (85 tests passing) - All schemas follow Zod-first approach with z.infer type exports Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- Added type exports to system/migration.zod.ts (8 operation types + MigrationDependency) - Added Input types to system/message-queue.zod.ts (TopicConfig, ConsumerConfig, DeadLetterQueue, MessageQueueConfig) - Added type exports to system/encryption.zod.ts, cache.zod.ts (already had Input types) - Added type export to ai/feedback-loop.zod.ts (MetadataSource) - Added Input type to kernel/context.zod.ts (KernelContext) - Added Input types to integration/connector/database.zod.ts (DatabasePoolConfig, SslConfig, CdcConfig, DatabaseTable) - Added type exports to ai/conversation.zod.ts (TextContent, ImageContent, FileContent, CodeContent with Input types where needed) Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- ui/view.zod.ts: Added 4 type exports (KanbanConfig, CalendarConfig, GanttConfig, NavigationMode) - automation/workflow.zod.ts: Added 9 type exports for workflow actions - FieldUpdateAction, EmailAlertAction, ConnectorActionRef - HttpCallAction + Input, TaskCreationAction - PushNotificationAction, CustomScriptAction + Input Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- automation/state-machine.zod.ts: Added 3 type exports (GuardRef, Event, StateMachine) - automation/flow.zod.ts: Added FlowVariable + FlowVariableInput types - automation/approval.zod.ts: Added ApprovalAction type export - data/filter.zod.ts: Added 5 operator type exports (EqualityOperator, ComparisonOperator, SetOperator, RangeOperator, StringOperator) Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- Documented all 56+ type exports added across 14 files - Listed remaining 65 missing exports for future work - Included recommendations and impact analysis Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
…tadata, and filter schemas Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
…and sharing schemas Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- Create schema-examples.zod.ts with 10 real-world examples - Demonstrate all base schema compositions (Timestamped, Auditable, etc.) - Show proper usage of validation patterns and length constraints - Include examples for simple to complex schema composition - Add 21 comprehensive test cases for all example schemas - Document best practices for schema creation - All 3287 tests passing, build successful Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- Create IMPLEMENTATION_SUMMARY.md documenting all improvements - Track Phase 1-2 completion metrics - Document 9 base schemas and 20+ validation patterns - Record 56+ type exports and 156+ .describe() annotations - Include before/after metrics and usage examples - Provide migration guide for developers - All 3287 tests passing, builds successful Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
- Create FINAL_SUMMARY.md with complete metrics and deliverables - Document all 9 base schemas and 20+ validation patterns - Track 56+ type exports, 156+ .describe() annotations, 88+ new tests - Include impact analysis and best practices - Record 100% test pass rate and 0 security vulnerabilities - Provide complete acceptance criteria verification - Ready for review and merge Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>
… in Feature, License, and Plan schemas
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Pull request overview
This PR expands and refines the generated JSON Schema protocol surface (notably around kernel plugin/package management and API versioning), adds several new schemas, and improves schema documentation consistency by adding/adjusting description fields and fixing $ref targets.
Changes:
- Added new kernel JSON Schemas for SBOM, plugin trust/quality/statistics, dynamic plugin loading, and dependency graph modeling.
- Updated multiple existing schemas with new configuration fields (e.g., plugin sandboxing IPC + scope, hot reload production safety) and improved descriptions.
- Removed a set of hub/api JSON Schema artifacts while renaming/fixing
$reftargets in remaining ones.
Reviewed changes
Copilot reviewed 117 out of 117 changed files in this pull request and generated 6 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/spec/json-schema/kernel/SBOM.json | Adds SBOM schema for plugin component inventory/export. |
| packages/spec/json-schema/kernel/PluginVendor.json | Fixes $ref/definition name to align with file intent. |
| packages/spec/json-schema/kernel/PluginTrustScore.json | Adds trust score model for plugins. |
| packages/spec/json-schema/kernel/PluginStatistics.json | Adds plugin statistics schema (downloads/ratings/etc.). |
| packages/spec/json-schema/kernel/PluginSource.json | Adds plugin source locator schema (npm/git/url/etc.). |
| packages/spec/json-schema/kernel/PluginSearchFilters.json | Fixes $ref/definition name to align with file intent. |
| packages/spec/json-schema/kernel/PluginSandboxing.json | Extends sandboxing config with scope + IPC settings. |
| packages/spec/json-schema/kernel/PluginRegistryEntry.json | Renames root definition and adds quality/statistics + timestamps to registry entries. |
| packages/spec/json-schema/kernel/PluginQualityMetrics.json | Adds plugin quality metrics schema. |
| packages/spec/json-schema/kernel/PluginLoadingState.json | Extends plugin loading state enum with unload states. |
| packages/spec/json-schema/kernel/PluginLoadingEvent.json | Extends plugin loading event enum with dynamic events. |
| packages/spec/json-schema/kernel/PluginLoadingConfig.json | Adds environment + production safety + sandbox scope/IPC configuration. |
| packages/spec/json-schema/kernel/PluginInstallConfig.json | Adds install config schema for plugin installation options. |
| packages/spec/json-schema/kernel/PluginHotReload.json | Adds environment + production safety configuration to hot reload schema. |
| packages/spec/json-schema/kernel/PluginDiscoverySource.json | Adds discrete discovery source schema for runtime discovery. |
| packages/spec/json-schema/kernel/PluginDiscoveryConfig.json | Adds discovery subsystem config schema. |
| packages/spec/json-schema/kernel/PackageDependencyConflict.json | Adds dependency conflict schema for resolution workflows. |
| packages/spec/json-schema/kernel/PackageDependency.json | Adds package dependency schema with constraint/type/resolution fields. |
| packages/spec/json-schema/kernel/Manifest.json | Adds plugin runtime config fields and reorders default/description fields for consistency. |
| packages/spec/json-schema/kernel/ListPackagesResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/InstalledPackage.json | Keeps installed package schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/InstallPackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/InstallPackageRequest.json | Keeps request schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/GetPackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/FeatureStrategy.json | Adds description to strategy enum. |
| packages/spec/json-schema/kernel/FeatureFlag.json | Adds/clarifies descriptions for feature flag fields. |
| packages/spec/json-schema/kernel/EnablePackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/DynamicUnloadRequest.json | Adds schema for runtime plugin unload operation. |
| packages/spec/json-schema/kernel/DynamicPluginResult.json | Adds schema describing results of dynamic plugin operations. |
| packages/spec/json-schema/kernel/DynamicPluginOperation.json | Adds enum schema for dynamic plugin operation types. |
| packages/spec/json-schema/kernel/DynamicLoadingConfig.json | Adds schema for dynamic plugin loading subsystem configuration. |
| packages/spec/json-schema/kernel/DynamicLoadRequest.json | Adds schema for runtime plugin load operation. |
| packages/spec/json-schema/kernel/DisablePackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/kernel/DependencyGraphNode.json | Adds schema for resolved dependency graph nodes. |
| packages/spec/json-schema/kernel/DependencyGraph.json | Adds schema for full dependency graph (nodes/edges/stats). |
| packages/spec/json-schema/kernel/ActivationEvent.json | Adds schema for lazy activation triggers. |
| packages/spec/json-schema/identity/Role.json | Improves descriptions for role hierarchy and role description. |
| packages/spec/json-schema/hub/TenantPlacementPolicy.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/SubscriptionStatus.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/SpaceSubscription.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/ReplicationJob.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/Region.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/PluginVersion.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/PluginPricing.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/Plan.json | Adds missing descriptions for display/pricing fields. |
| packages/spec/json-schema/hub/PackageDependencyResolutionResult.json | Fixes $ref/definition name to align with file intent. |
| packages/spec/json-schema/hub/PackageDependencyConflict.json | Fixes $ref/definition name to align with file intent. |
| packages/spec/json-schema/hub/MarketplacePlugin.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/License.json | Improves descriptions for license semantics and signature. |
| packages/spec/json-schema/hub/HubInstance.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/GlobalRegistryEntry.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/Feature.json | Adds missing descriptions and clarifies metric semantics. |
| packages/spec/json-schema/hub/EdgeLocation.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/DeploymentTarget.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/DependencyRequirement.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/ConflictReport.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/ComposerRequest.json | Removes hub schema artifact. |
| packages/spec/json-schema/hub/BillOfMaterials.json | Removes hub schema artifact. |
| packages/spec/json-schema/data/TransformType.json | Adds description to transform enum. |
| packages/spec/json-schema/data/StringOperator.json | Adds descriptions for string operators. |
| packages/spec/json-schema/data/SpecialOperator.json | Adds descriptions for null/exists operators. |
| packages/spec/json-schema/data/SetOperator.json | Adds descriptions for set operators. |
| packages/spec/json-schema/data/RangeOperator.json | Adds description for between operator semantics. |
| packages/spec/json-schema/data/QueryFilter.json | Adds description for query filter clause. |
| packages/spec/json-schema/data/Mapping.json | Improves descriptions across mapping import/transform fields. |
| packages/spec/json-schema/data/FieldOperators.json | Adds operator descriptions for filter operators. |
| packages/spec/json-schema/data/FieldMapping.json | Improves descriptions for mapping transform params. |
| packages/spec/json-schema/data/EqualityOperator.json | Adds descriptions for equality operators. |
| packages/spec/json-schema/data/DatasetMode.json | Adds description to dataset conflict strategy enum. |
| packages/spec/json-schema/data/Dataset.json | Reorders default/description fields for consistency. |
| packages/spec/json-schema/data/ComparisonOperator.json | Adds descriptions for comparison operators. |
| packages/spec/json-schema/api/VersioningStrategy.json | Adds versioning strategy enum schema. |
| packages/spec/json-schema/api/VersioningConfig.json | Adds version negotiation configuration schema with lifecycle metadata. |
| packages/spec/json-schema/api/VersionStatus.json | Adds version status enum schema. |
| packages/spec/json-schema/api/VersionNegotiationResponse.json | Adds schema for version negotiation discovery/response payload. |
| packages/spec/json-schema/api/VersionDefinition.json | Adds reusable version metadata schema. |
| packages/spec/json-schema/api/ValidateLicenseResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ValidateLicenseRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/UpdateTenantRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/TenantResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/RouterConfig.json | Extends router endpoints defaults to include additional protocols (ui/workflow/etc.). |
| packages/spec/json-schema/api/RevokeLicenseRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/PluginVersionInfo.json | Removes API schema artifact. |
| packages/spec/json-schema/api/PaginationResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/PaginationRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ListTenantsResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ListTenantsRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ListSpacesRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ListPackagesResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/api/ListMarketplaceRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ListLicensesResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/ListLicensesRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/LicenseResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/IssueLicenseRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/InstallPluginResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/InstallPluginRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/InstallPackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/api/InstallPackageRequest.json | Keeps request schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/api/HubMetricsResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/HubHealthResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/GetPluginVersionsResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/GetPluginVersionsRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/GetPackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/api/GetMarketplacePluginRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/GetBuildStatusRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/EnablePackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/api/DispatcherRoute.json | Reorders default/description fields for consistency. |
| packages/spec/json-schema/api/DispatcherConfig.json | Reorders default/description fields for consistency. |
| packages/spec/json-schema/api/DisablePackageResponse.json | Keeps response schema in sync with manifest plugin config enhancements. |
| packages/spec/json-schema/api/ConceptListResponse.json | Adds descriptions for concept list entry fields. |
| packages/spec/json-schema/api/CompileManifestRequest.json | Removes API schema artifact. |
| packages/spec/json-schema/api/BuildStatusResponse.json | Removes API schema artifact. |
| packages/spec/json-schema/api/AnalyticsSqlResponse.json | Adds descriptions for SQL dry-run payload. |
| packages/spec/json-schema/api/AnalyticsResultResponse.json | Adds descriptions for analytics result fields. |
| packages/spec/json-schema/api/AnalyticsMetadataResponse.json | Adds description for analytics metadata payload. |
| packages/spec/json-schema/api/AnalyticsEndpoint.json | Adds description to analytics endpoint enum. |
| packages/spec/json-schema/ai/Resolution.json | Improves descriptions in AI feedback/resolution schemas. |
| packages/spec/json-schema/ai/MetadataSource.json | Adds descriptions for metadata source location fields. |
| packages/spec/json-schema/ai/Issue.json | Adds descriptions for issue fields and nested source info. |
| packages/spec/json-schema/ai/FeedbackLoop.json | Adds descriptions for feedback loop, issue, and resolution fields. |
| packages/spec/docs/TYPE_EXPORT_PROGRESS.md | Adds a progress report documenting type export work. |
Copilot
AI
Feb 9, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This inlines the full PackageDependency structure even though packages/spec/json-schema/kernel/PackageDependency.json exists. This duplication is likely to drift over time (and the same pattern appears in DependencyGraphNode.json). Prefer referencing the shared definition via $ref (or pulling the schema into a local definitions entry and $ref-ing it) so dependency shape changes are centralized.
| "$ref": "PackageDependency.json" |
Copilot
AI
Feb 9, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The quality and statistics blocks appear to duplicate the standalone PluginQualityMetrics.json and PluginStatistics.json schemas. To avoid schema drift, consider using $ref to reuse those shared schemas here instead of copying their structure inline.
| "$ref": "./PluginQualityMetrics.json#/definitions/PluginQualityMetrics" |
Copilot
AI
Feb 9, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The root schema description was removed in this change (previously it was present, albeit inaccurate). Since this file now defines PluginRegistryEntry, it would be helpful to add back an accurate description at the root object so generated docs and schema browsers remain informative.
Copilot
AI
Feb 9, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The trust level taxonomy here (verified|trusted|community|untrusted) doesn’t match PluginTrustScore.level (verified|trusted|neutral|untrusted|blocked). If these concepts are intended to interoperate (filtering by computed trust level), align the enums (or document a mapping) to prevent clients from being unable to express valid filter values like neutral/blocked.
| "description": "Minimum computed trust level for plugins. Uses PluginTrustScore.level taxonomy: verified | trusted | neutral | untrusted | blocked. Legacy value 'community' is accepted as an alias for 'neutral'.", | |
| "enum": [ | |
| "verified", | |
| "trusted", | |
| "neutral", | |
| "community", | |
| "untrusted", | |
| "blocked" |
Copilot
AI
Feb 9, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This duplicates the newly added kernel/ActivationEvent.json schema shape inline. Consider replacing the inline object with a $ref to ActivationEvent (or a local definitions reference) so activation event constraints and documentation stay consistent across schemas.
| "$ref": "./ActivationEvent.json" |
Copilot
AI
Feb 9, 2026
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
These fields are described as ISO 8601 dates, but they don’t declare a format. Consider using format: \"date\" (or date-time if you expect timestamps) to improve validation and tooling interoperability.
| "type": "string", | |
| "format": "date", | |
| "description": "Release date (ISO 8601, e.g., \"2025-01-15\")" | |
| }, | |
| "deprecatedAt": { | |
| "type": "string", | |
| "format": "date", | |
| "description": "Deprecation date (ISO 8601). Only set for deprecated/retired versions" | |
| }, | |
| "sunsetAt": { | |
| "type": "string", | |
| "format": "date", |
Systematic audit of 142 Zod protocol files revealed widespread duplication of timestamp/audit fields and inconsistent validation patterns. This PR introduces reusable composition primitives and centralized validation.
Deliverables
Base Schemas (
shared/base-schemas.zod.ts)Timestamped,Auditable,SoftDeletable,NamedEntity,Versionable,Taggable,Ownable,Activatable,MetadataContainerValidation Patterns (
shared/validation-patterns.zod.ts)SNAKE_CASE_PATTERN,SEMVER_PATTERN,EMAIL_PATTERN,UUID_V4_PATTERN, etc.SnakeCaseString,EmailString,UuidString, etc.LENGTH_CONSTRAINTSobject for consistent field length validationType Safety
z.inferexports across 15 filesz.inputexports for schemas with.default()or.transform()Documentation
.describe()annotations (6,169 total)Example
Before:
After:
Impact
See
docs/SHARED_SCHEMAS_GUIDE.mdfor usage patterns.Original prompt
Created from VS Code.
💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.